Skip to main content

Setting up validation rules

For examples of rules, see Examples.

For a list of supported CSS syntax, see CSS Syntax.

For instructions on how to install the plugin, see Install the Mad Quality Plugin.

Setting up rules requires Microsoft Excel, or a software that can edit .xlsx files.

A rule consists of these parts:

Name

  • The name of the rule, for example "MS-20210417104127".
    This string appears in the report and makes it easier to find the rule in the ruleset.

Enabled

  • Enables (TRUE) or disables (FALSE) the rule.
    If you disable a rule, the plugin ignores it in the ruleset (does not run it).

Description

Message

  • A detailed message about the violation.
    This string appears in the report.
    For example "Avoid using acronyms in a title or heading."
    • You can add %s and %t to your message string to include the Regular Expression matches. For example, for a rule with the Word function with the parameter checkbox:check box, the message could be Do not write: '%s'. Write: '%t'.. The report would show this to the writer: Do not write: 'checkbox'. Write: 'check box'.

Type

  • The type determines whether to assert or report the presence of a pattern.
    • If you select Assert, the report shows a rule violation only if the pattern does not appear in your content.
      For example, to check if H1 appears, enter h1:nth-of-type(1) in the Context column.
      This rule would be violated only if a topic / snippet does not contain one <h1>.
    • If you select Report, the report shows a rule violation only if the pattern does appear in your content.
      For example, to check if H-tags contain a <br /> tag, enter :header:has(br) in the Context column.
      This rule would be violated only if a heading tag contains a <br /> tag.

Context

  • The CSS-based context to apply the rule in. For example, to apply it to all paragraph <p> elements, the context would be p.
    I recommend this reference: MDN CSS selectors

IgnoreContext

  • The CSS-based context to_not_ apply the rule in.

It is possible to use XPath in the context and IgnoreContext.
Examples:
- To match all paragraphs, enter: xpath:.//p
- To match a topic that has the xml:lang="VALUE", enter: xpath:.//html[@xml:lang]

Function

  • The function of the rule. Each function, except the None function takes one or more parameters, configured in the Parameters column.

    FunctionDescriptionClarification / Example
    NoneThe rule just asserts or reports the presence of the context element.To find a heading wrapped in a paragraph tag, you can configure this Context:
    p > h1
    RegexThe rule uses the RegEx syntax from the Parameters column to check for the pattern match only in the inner text value of an element from the Context column.
    All inline elements are unbound.    		The rule analyzes the string
    <p>Lorem <b>ipsum</b> dolor</p>
    as
    Lorem ipsum dolor.
    RawRegexThe rule uses the RegEx syntax from the Parameters column to check for the pattern match in the entire element from the Context column.
    All inline elements are kept.    		The rule analyzes the string
    <p>Lorem <b>ipsum</b> dolor</p>
    literally as
    <p>Lorem <b>ipsum</b> dolor</p>.
    For example, to find two adjacent variables with a missing space between them, you can configure:
    - Context = p, li
    - Parameters = <\/MadCap:variable><MadCap:variable
    For example, to find the <![CDATA[]]> tag, you can configure:
    - Context = h1, h2, h3, h4, h5, h6, p
    - Parameters = \<!\[CDATA\[
    RegexInlineThe rule uses the RegEx syntax from the Parameters column to check for the pattern match only in the inner text value of an element from the Context column.
    All inline elements are kept.    		The rule analyzes the string
    <p>Lorem <b>ipsum</b> dolor</p>
    as
    Lorem <b>ipsum</b> dolor.
    Note - Try this function if the RawRegex function does not find a match.
    For example to check if the text in a heading starts with a space, you can configure:
    - Context = :header
    - Parameters = ^[ ]{1,3}(.+?)
    WordThe rule checks for the presence of a single word in the context element.
    This function supports a RegEx syntax in the left-hand side of the parameter the Parameters column.    		checkbox would match elements with that word.
    Optionally - you can suggest an alternative to the matched word. Add a colon and the replacement word:
    checkbox:check box.
    This provides a suggestion for replacement to the writer.
    ListOfWordsThis rule works like the Word rule, but on a list of words.
    This function supports a RegEx syntax in the left-hand side of the parameter the Parameters column.    		To find content that contains the words checkbox or intelligent, enter in the Parameters column:
    checkbox,intelligent.
    To also suggest replacement words, enter in the Parameters column:
    checkbox:check box,intelligent:smart
    FileNameRegexThe rule uses the RegEx syntax from the Parameters column to check the file names.To find file names that contain spaces, you can configure:
    \s{1,}
    To find file names that contain capital letters, you can configure:
    [A-Z]
    ReadabilityMatches elements with a readability score lower than the value you configured in the Parameters column60
    RegexElementOnlyThe rule uses the RegEx syntax from the Parameters column to check for the pattern match only in the text directly owned by the element from the Context column, excluding text in child elements.The rule analyzes the string
    <p>Lorem <b>ipsum</b> dolor</p>
    as
    Lorem dolor
    (note the double space where the child element was).
    This is useful when you need to check patterns in the parent element's text while ignoring content in child elements.

    To develop and test regular expressions, I recommend these web sites: RegEx101, RegEx Pal.

IgnoreCase

  • For rules that contain RegEx in the Parameters column, this setting determines whether to ignore (TRUE) or not (FALSE) the letter-case of the matching text.

Parameters

  • The parameters for the different functions.
    For example, a RegEx syntax.
    See the Function section above.

Score

  • A penalty score to apply when a rule is broken.
    Use this to let writers know how serious a broken rule is.
    You decide on the scale and its meaning.

FileFilters

  • This is a comma-separated wildcard based text that lets you assign rules to different file types, or files with a specfic prefix.
    For example *.htm,*.html,*.flsnp matches topics and snippets.